﻿/*
 * Copyright 2011 Edward L. Stauff.                           Contact: <EdStauff@gmail.com>.
 * 
 * This file, "CustomAttributes.cs", is part of the "Stauffware.Common.Xml.Xerialization" 
 * library.  "Stauffware.Common.Xml.Xerialization" is free software: you can redistribute 
 * it and/or modify it under the terms of the GNU Lesser Public License as published by 
 * the Free Software Foundation, either version 3 of the License, or (at your option) 
 * any later version.
 * 
 * "Stauffware.Common.Xml.Xerialization" is distributed in the hope that it will be 
 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser Public License for more 
 * details.
 * 
 * You should have received a copy of the GNU Lesser Public License along with 
 * "Stauffware.Common.Xml.Xerialization".  If not, see <http://www.gnu.org/licenses/>.
 */
using System;
using System.Collections.Generic;
using System.Xml;
using System.Reflection;
using System.Text;
using Stauffware.Common.Core;

namespace Stauffware.Common.Xml.Xerialization
{
	//#################################################################################
	/// <summary>
	/// Marks a class (or struct) as being xerializable.  If not marked with this attribute,
	/// a class (or struct) will not be xerializable.
	/// </summary>

	[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct, Inherited=false, AllowMultiple=false)]
	public class XerialTypeAttribute : Attribute
	{
		/// <summary>
		/// A name to use for the XML attribute or element.
		/// If not specified, a default name is chosen based on the name of the type.
		/// This can be overridden on individual class members by XerialMemberAttribute.
		/// </summary>
		public string XmlName;

		/// <summary>
		/// Specifies what fields in the class to xerialize by default.
		/// This can be overridden on individual class members by XerialMemberAttribute.
		/// </summary>
		public MemberInclusion IncludeFields = MemberInclusion.All;

		/// <summary>
		/// Specifies what properties in the class to xerialize by default.
		/// This can be overridden on individual class members by XerialMemberAttribute.
		/// </summary>
		public MemberInclusion IncludeProperties = MemberInclusion.All;

		/// <summary>
		/// Specifies the default XML encoding for fields. If not specified, or if set 
		/// to MemberValueEncoding.Default, the default storage type will be Attribute
		/// for scalar value types and strings, and NestedElements for reference types.
		/// This can be overridden on individual class members by XerialMemberAttribute.
		/// </summary>
		public MemberValueEncoding FieldEncoding = MemberValueEncoding.Default;

		/// <summary>
		/// Specifies the default XML encoding for properties. If not specified, or if set 
		/// to MemberValueEncoding.Default, the default storage type will be Attribute
		/// for scalar value types and strings, and NestedElements for reference types.
		/// </summary>
		/// This can be overridden on individual class members by XerialMemberAttribute.
		public MemberValueEncoding PropertyEncoding = MemberValueEncoding.Default;

		/// <summary>
		/// Specifies whether members (both fields and properties) are optional by default.
		/// This can be overridden on individual class members by XerialMemberAttribute.
		/// If not specified, it defaults to XerialContext.DefaultMemberOptionality.
		/// </summary>
		public bool? MembersAreOptional = null;

		/// <summary>
		/// Specifies whether to ignore unknown XML elements or report them as errors.
		/// </summary>
		public bool? IgnoreUnknownElements;

		/// <summary>
		/// Specifies whether to ignore unknown XML attributes or report them as errors.
		/// </summary>
		public bool? IgnoreUnknownAttributes;

		/// <summary>
		/// Help string for run-time documentation.
		/// </summary>
		public string Help;

		//-----------------------------------------------------------------------------
		/// <summary>
		/// Returns the XerialTypeAttribute for the given type, or null.
		/// </summary>

		internal static XerialTypeAttribute GetFrom (Type t)
		{
			object[] attrs = t.GetCustomAttributes(typeof(XerialTypeAttribute), false);
			if (attrs.Length == 0)
				return null;
			Assert.Condition(attrs.Length == 1);
			return (XerialTypeAttribute)attrs[0];
		}

		//-----------------------------------------------------------------------------
	}

	//#################################################################################
	/// <summary>
	/// Specifies xerialization options for an individual class member (field or property).
	/// </summary>

	[AttributeUsage(AttributeTargets.Field | AttributeTargets.Property, Inherited=false, AllowMultiple=false)]
	public class XerialMemberAttribute : Attribute
	{
		/// <summary>
		/// Specifies the name to use for the XML attribute or element in which the
		/// member value will be stored.  If not specified, it defaults to the name 
		/// of the field or property.
		/// </summary>
		public string XmlName;

		/// <summary>
		/// Specifies the XML encoding for the member. If not specified, or if set 
		/// to MemberValueEncoding.Default, it defaults to the value specified by
		/// the XerialTypeAttribute for the enclosing class.
		/// </summary>
		public MemberValueEncoding Encoding = MemberValueEncoding.Default;

		/// <summary>
		/// Specifies whether the member is optional. If not specified, it defaults to 
		/// the value specified by the XerialTypeAttribute for the enclosing class.
		/// </summary>
	//	public bool? IsOptional = null;
		public bool IsOptional
		{
			get { Require.Condition(this.IsOptionalWasSet); return this._isOptional; }
			set { this._isOptional = value; this.IsOptionalWasSet = true; }
		}
		private Boolean _isOptional;

		/// <summary> Gets whether the IsOptional property was set. </summary>
		public bool IsOptionalWasSet { get; private set; }

		/// <summary>
		/// Help string for run-time documentation.
		/// </summary>
		public string Help;

		/// <summary>
		/// The name of a method that will be used for reading the member value from XML.
		/// If provided, the read method must be callable as a MemberReader delegate.
		/// </summary>
		public string ReadMethod;

		/// <summary>
		/// The name of a method that will be used for writing the member value to XML.
		/// If provided, the write method must be callable as a MemberWriter delegate.
		/// </summary>
		public string WriteMethod;

		//-----------------------------------------------------------------------------
		/// <summary>
		/// Returns the XerialMemberAttribute for the given member, or null.
		/// </summary>

		internal static XerialMemberAttribute GetFrom (MemberInfo mi)
		{
			object[] attrs = mi.GetCustomAttributes(typeof(XerialMemberAttribute), false);
			if (attrs.Length == 0)
				return null;
			Assert.Condition(attrs.Length == 1);
			return (XerialMemberAttribute)attrs[0];
		}

		//-----------------------------------------------------------------------------
	}

	//#################################################################################
	/// <summary>
	/// Indicates that the static method should be used for reading an abstract class from XML.
	/// The method must take two arguments of type XerialContext and NiceXmlReader,
	/// and return a new object created from the XML data.
	/// </summary>

	[AttributeUsage(AttributeTargets.Method, Inherited=false, AllowMultiple=false)]
	public class XerialFactory : Attribute
	{
	}

	//#################################################################################
}
